package com.wg.net.session;

import com.wg.net.DisconnectReason;
import com.wg.net.SendResult;

/**
 * 会话接口（定义TCP/WebSocket连接的通用行为）
 * <p>
 * 职责：
 * - 管理会话元数据（连接ID、PeerID、本地/远程地址）
 * - 提供消息收发、连接状态管理（关闭、断开）
 * - 支持自定义数据存储（业务上下文）
 *
 * @author 少爷123
 */
public interface ISession {

    /**
     * 获取连接唯一标识（自增ID）
     *
     * @return 长整型连接ID（应用生命周期内唯一）
     */
    long getConnectionId();

    /**
     * 获取会话对端标识（字符串形式，如WebSocket的Sec-WebSocket-Key）
     *
     * @return 对端ID字符串
     */
    String getPeerId();

    /**
     * 发送消息到对端（阻塞或异步，取决于底层实现）
     *
     * @param data 待发送的字节数据
     * @return 发送结果（成功/失败/连接断开等）
     */
    SendResult send(byte[] data);

    /**
     * 刷新输出缓冲区（强制发送待写数据）
     */
    void flush();

    /**
     * 关闭会话（优雅断开连接）
     */
    void close();

    /**
     * 主动断开连接（指定断开原因）
     *
     * @param reason 断开原因（如超时、客户端主动关闭）
     */
    void disconnect(DisconnectReason reason);

    /**
     * 获取本地绑定端口
     *
     * @return 本地端口号（0表示未绑定）
     */
    int getLocalPort();

    /**
     * 获取本地绑定IP地址
     *
     * @return 本地IP字符串（如"192.168.1.100"）
     */
    String getLocalIp();

    /**
     * 获取对端连接端口
     *
     * @return 对端端口号
     */
    int getRemotePort();

    /**
     * 获取对端连接IP地址
     *
     * @return 对端IP字符串
     */
    String getRemoteIp();

    /**
     * 获取会话自定义数据（业务上下文）
     *
     * @return 自定义数据对象（可能为null）
     */
    Object getUserData();

    /**
     * 设置会话自定义数据（业务上下文）
     *
     * @param data 自定义数据对象（允许null）
     */
    void setUserData(Object data);
}